Face Authentication API (v2)

The following document highlights the details of the Face Authentication API (v2).

API Description

Objective

The Face Authentication API (v2) verifies if the selfie provided in the request matches the image corresponding to a unique identifier (UID) in the database.

Input	Output
The selfie of the customer and the unique transaction ID.	It reflects if the database contains a record that matches the selfie.

API URL

https://ind-orion.hyperverge.co/v2/faceAuth

API Endpoint

faceAuth

Overview

The Face Authentication API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Face Authentication API.

Headers

The following table provides the complete information on the request headers for the Face Authentication API.

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload.	multipart/form-data
accept	Mandatory	This parameter defines the media type for the response.	application/json
appId	Mandatory	Application ID shared by HyperVerge.	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge.	N/A. This is a unique value.

Inputs

The following table provides the complete information on the input parameters used in the request body for the Face Authentication API.

Parameter	Mandatory / Optional	Type	Description	Input Format
transactionId	Mandatory	string	The unique identifier for the customer's application.	String
uidType	Mandatory	string	The type of the unique identifier. It can be the transaction ID or any other unique identifier for the enrolment. Note It is commonly configured as "transaction_id".	String (e.g. transaction_id)
uid	Mandatory	string	The unique identifier for the record in your database used during enrolment. Note It is commonly configured as the transaction ID for the record.	String
selfie	Mandatory	file	This is the selfie image of the user. The maximum image size is 6 MB.	Image file (max 6 MB)

Additional Quality and Fraud Checks

In addition to its liveness and face match checks, the Face Authentication API can also execute additional checks on the image. You can view the complete list under the Additional Checks For Liveness page.

Note

If you include any quality check parameter in the request, the result is added to the qualityChecks object in the response.

Request

The following code snippet demonstrates a standard curl request for the Face Authentication API:

curl --location --request POST 'https://ind-orion.hyperverge.co/v2/faceAuth' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--form 'transactionId="<Enter_the_HyperVerge_transactionID>"' \
--form 'uidType="transaction_id"' \
--form 'uid="<Enter_the_Unique_Identifier>"' \
--form 'selfie=@"<path_to_selfie_image>"' \
--form 'ignoreSelfieQuality="<yes_or_no>"'

Success Response

The following code snippet demonstrates a response for a matching record in the database from the Face Authentication API:

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {
      "matchScore": 99,
      "match": "yes"
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

Success Response Details

The following table provides the details of the parameters in a successful response from the Face Authentication API.

Parameter	Type	Description
status	String	Indicates whether the request was successful.
statusCode	Integer	HTTP status code of the response.
metaData.requestId	String	Unique identifier for the request.
metaData.transactionId	String	The transaction ID sent in the request.
result.data.matchScore	Integer	Numeric face match score (0–100).
result.data.match	String	Whether the selfie matches the enrolled image ("yes" or "no").
result.summary.action	String	It displays the recommended decision for the customer. It can take any of the values from the following table. Action Recommendation pass You can proceed with the application. Returned when the selfie matches the enrolled image (match=yes). fail Do not proceed. Returned for face mismatch (E200, match score 0–20), non-live selfie (E202), or no record found (E203). See result.summary.details for code and message. manualReview Requires manual review for further approval or rejection. Returned when match score is in the grey zone (E204, match score 21–50). retake Ask the user to retake the selfie. Returned when selfie quality is insufficient (E201).
result.summary.details	Array	List of detail objects containing code (e.g. E200, E201, E202, E203, E204) and message when applicable.

Failure Responses

The following are the failure responses for the Face Authentication API. Alternatively, you can find the details of the failure responses listed here.

Face Mismatch (E200)

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {
      "matchScore": 10,
      "match": "no"
    },
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E200",
          "message": "Face mismatch"
        }
      ]
    }
  }
}

Face Mismatch - Manual Review (E204)

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {
      "matchScore": 35,
      "match": "no"
    },
    "summary": {
      "action": "manualReview",
      "details": [
        {
          "code": "E204",
          "message": "Face mismatch"
        }
      ]
    }
  }
}

Selfie Quality Issue

{
  "status": "failure",
  "statusCode": 422,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "retake",
      "details": [
        {
          "code": "E201",
          "message": "Selfie Quality is Insufficient"
        }
      ]
    },
    "error": "Selfie Quality is Insufficient"
  }
}

Face Not Detected

{
    "error": "Face not detected in Selfie image",
    "statusCode": 400,
    "status": "failure",
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
}

Non-Live Selfie

{
  "status": "failure",
  "statusCode": 422,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E202",
          "message": "Selfie is Not Live"
        }
      ]
    },
    "error": "Selfie is Not Live"
  }
}

No Record Found

{
  "status": "failure",
  "statusCode": 404,
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E203",
          "message": "No Record Found"
        }
      ]
    },
    "error": "No Record Found"
  }
}

Error Responses

The following are the error responses for the Face Authentication API.

Missing Transaction ID

{
  "error": "\"transactionId\" is required",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Missing/Invalid Credentials

{
  "error": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

LenderNode Not Found

{
  "error": "Lendernode not found",
  "statusCode": 404,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Service Unavailable

{
  "error": "Rate limit exceeded",
  "statusCode": 429,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Internal Server Error

{
  "error": "Internal Server Error",
  "statusCode": 500,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Error Response Details

A response from the Face Authentication API can be either a failure or an error. The following table lists all failure and error responses, along with their respective status codes, error messages, descriptions, and suggested resolutions.

Status Code	Error Message	Error Description	Error Resolution
200	Face mismatch (E200)	The face matching score is 0–20, resulting in a failed match. summary.action is fail.	Retry with a clearer selfie or ensure the user's face matches the enrolled image.
200	Face mismatch – manual review (E204)	Match score is in the grey zone (21–50). summary.action is manualReview.	Review the case manually or retry with a better quality selfie.
422	Selfie Quality is Insufficient (E201)	The selfie blur check failed. summary.action is retake.	Ask the user to retake the selfie with better lighting and clarity.
422	Selfie is Not Live (E202)	The liveness check failed. summary.action is fail.	Use a live selfie capture flow and retry.
404	No Record Found (E203)	UID not enrolled in the database. summary.action is fail.	Verify the transaction ID and ensure enrolment was completed for this user.
400	Face Not Detected	The Face Authentication API failed to detect a face in the selfie image.	Ensure the selfie contains a single, clearly visible face and retry.
400	"transactionId" is required	The request does not contain the transaction identification number.	Include a valid transactionId in the request body.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.	Provide valid appId and appKey headers.
404	Lendernode not found	The Face Authentication API failed to get the lender node.	Contact the HyperVerge team to verify your configuration.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.	Throttle requests or contact HyperVerge to increase the rate limit.
500	Internal Server Error	There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution.	Contact the HyperVerge team for resolution.